<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Shape query | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="shape-queries.html" title="Shape queries">
<link rel="prev" href="shape-queries.html" title="Shape queries">
<link rel="next" href="joining-queries.html" title="Joining queries">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="query-dsl.html">Query DSL</a></span>
»
<span class="breadcrumb-link"><a href="shape-queries.html">Shape queries</a></span>
»
<span class="breadcrumb-node">Shape query</span>
</div>
<div class="navheader">
<span class="prev">
<a href="shape-queries.html">« Shape queries</a>
</span>
<span class="next">
<a href="joining-queries.html">Joining queries »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="query-dsl-shape-query"></a>Shape query<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/shape-query.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>Queries documents that contain fields indexed using the <code class="literal">shape</code> type.</p>
<p>Requires the <a class="xref" href="shape.html" title="Shape datatype"><code class="literal">shape</code> Mapping</a>.</p>
<p>The query supports two ways of defining the target shape, either by
providing a whole shape definition, or by referencing the name, or id, of a shape
pre-indexed in another index. Both formats are defined below with
examples.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_inline_shape_definition_2"></a>Inline Shape Definition<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/shape-query.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Similar to the <code class="literal">geo_shape</code> query, the <code class="literal">shape</code> query uses
<a href="http://www.geojson.org" class="ulink" target="_top">GeoJSON</a> or
<a href="https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry" class="ulink" target="_top">Well Known Text</a>
(WKT) to represent shapes.</p>
<p>Given the following index:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /example
{
    "mappings": {
        "properties": {
            "geometry": {
                "type": "shape"
            }
        }
    }
}

PUT /example/_doc/1?refresh=wait_for
{
    "name": "Lucky Landing",
    "geometry": {
        "type": "point",
        "coordinates": [1355.400544, 5255.530286]
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/197.console"></div>
<p>The following query will find the point using the Elasticsearch’s
<code class="literal">envelope</code> GeoJSON extension:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /example/_search
{
    "query":{
        "shape": {
            "geometry": {
                "shape": {
                    "type": "envelope",
                    "coordinates" : [[1355.0, 5355.0], [1400.0, 5200.0]]
                },
                "relation": "within"
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/198.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_pre_indexed_shape_2"></a>Pre-Indexed Shape<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/shape-query.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The Query also supports using a shape which has already been indexed in
another index. This is particularly useful for when
you have a pre-defined list of shapes which are useful to your
application and you want to reference this using a logical name (for
example <em>New Zealand</em>) rather than having to provide their coordinates
each time. In this situation it is only necessary to provide:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">id</code> - The ID of the document that containing the pre-indexed shape.
</li>
<li class="listitem">
<code class="literal">index</code> - Name of the index where the pre-indexed shape is. Defaults
to <em>shapes</em>.
</li>
<li class="listitem">
<code class="literal">path</code> - The field specified as path containing the pre-indexed shape.
Defaults to <em>shape</em>.
</li>
<li class="listitem">
<code class="literal">routing</code> - The routing of the shape document if required.
</li>
</ul>
</div>
<p>The following is an example of using the Filter with a pre-indexed
shape:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /shapes
{
    "mappings": {
        "properties": {
            "geometry": {
                "type": "shape"
            }
        }
    }
}

PUT /shapes/_doc/footprint
{
    "geometry": {
        "type": "envelope",
        "coordinates" : [[1355.0, 5355.0], [1400.0, 5200.0]]
    }
}

GET /example/_search
{
    "query": {
        "shape": {
            "geometry": {
                "indexed_shape": {
                    "index": "shapes",
                    "id": "footprint",
                    "path": "geometry"
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/199.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_spatial_relations_2"></a>Spatial Relations<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/shape-query.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following is a complete list of spatial relation operators available:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">INTERSECTS</code> - (default) Return all documents whose <code class="literal">shape</code> field
intersects the query geometry.
</li>
<li class="listitem">
<code class="literal">DISJOINT</code> - Return all documents whose <code class="literal">shape</code> field
has nothing in common with the query geometry.
</li>
<li class="listitem">
<code class="literal">WITHIN</code> - Return all documents whose <code class="literal">shape</code> field
is within the query geometry.
</li>
<li class="listitem">
<code class="literal">CONTAINS</code> - Return all documents whose <code class="literal">shape</code> field
contains the query geometry.
</li>
</ul>
</div>
<h4>
<a id="_ignore_unmapped_5"></a>Ignore Unmapped<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/query-dsl/shape-query.asciidoc">edit</a>
</h4>
<p>When set to <code class="literal">true</code> the <code class="literal">ignore_unmapped</code> option will ignore an unmapped field
and will not match any documents for this query. This can be useful when
querying multiple indexes which might have different mappings. When set to
<code class="literal">false</code> (the default value) the query will throw an exception if the field
is not mapped.</p>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="shape-queries.html">« Shape queries</a>
</span>
<span class="next">
<a href="joining-queries.html">Joining queries »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
